---
title: ControlCloud
description: A dynamic filter display component that shows active filters as interactive pills with keyboard navigation and removal capabilities for enhanced data filtering interfaces.
---
import { 
  BasicControlCloud, 
  TimeBasedFilters, 
  MultipleFilterTypes, 
  EmptyState, 
  InteractiveExample 
} from "./control-cloud.examples";

## Overview

The ControlCloud component provides a dynamic way to display active filters as interactive pills. It's designed to show users what filters are currently applied to their data, with keyboard navigation, removal capabilities, and customizable formatting for enhanced data filtering interfaces.

## Usage

```tsx
import { ControlCloud } from "@unkey/ui";

export default function MyComponent() {
  const [filters, setFilters] = useState<FilterValue[]>([]);
  
  const removeFilter = (id: string) => {
    setFilters(filters.filter(f => f.id !== id));
  };
  
  const updateFilters = (newFilters: FilterValue[]) => {
    setFilters(newFilters);
  };
  
  const formatFieldName = (field: string): string => {
    return field.charAt(0).toUpperCase() + field.slice(1);
  };
  
  return (
    <ControlCloud
      filters={filters}
      removeFilter={removeFilter}
      updateFilters={updateFilters}
      formatFieldName={formatFieldName}
    />
  );
}
```

## Examples

### Basic ControlCloud
A simple example showing basic filter pills for status and method.

<BasicControlCloud />

### Time-Based Filters
Example with time range filters that use the TimestampInfo component for display.

<TimeBasedFilters />

### Multiple Filter Types
Demonstrates different filter types including status, method, path, and duration with custom value formatting.

<MultipleFilterTypes />

### Empty State
When no filters are applied, the component is hidden entirely.

<EmptyState />

### Interactive Example
Add filters dynamically and test keyboard navigation.

<InteractiveExample />

## Features

- **Interactive Filter Pills**: Each filter is displayed as a removable pill with field name, operator, and value
- **Keyboard Navigation**: Full keyboard support with arrow keys and vim-style navigation (h,j,k,l)
- **Keyboard Shortcuts**: 
  - `⌥+⇧+D` to clear all filters and set default time range
  - `⌥+⇧+C` to focus the first filter pill
- **Time Display**: Automatic timestamp formatting for time-based filters
- **Custom Formatting**: Configurable field name and value formatting
- **Accessibility**: Proper ARIA attributes and screen reader support
- **Responsive Design**: Adapts to different screen sizes

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `filters` | `FilterValue[]` | `[]` | Array of active filters to display |
| `removeFilter` | `(id: string) => void` | - | Function to remove a filter by ID |
| `updateFilters` | `(filters: FilterValue[]) => void` | - | Function to update the entire filter array |
| `formatFieldName` | `(field: string) => string` | - | Function to format field names for display |
| `formatValue` | `(value: string \| number, field: string) => string` | `defaultFormatValue` | Function to format values for display |
| `historicalWindow` | `number` | `12 * 60 * 60 * 1000` | Default time window in milliseconds for time-based shortcuts |

## FilterValue Type

```tsx
type FilterValue = {
  id: string;
  field: string;
  operator: "is" | "contains" | "gt" | "lt" | "gte" | "lte" | "startsWith" | "endsWith";
  value: string | number;
  metadata?: {
    colorClass?: string;
    icon?: React.ReactNode;
  };
};
```

## Structure

The ControlCloud component is composed of:

1. **Filter Pills Container** - Wrapper for all filter pills
2. **Individual Filter Pills** - Each filter displayed as a removable pill
3. **Keyboard Navigation System** - Handles focus and navigation
4. **Time Display Components** - Special formatting for time-based filters

## Styling

The component includes default styling with:

- Consistent pill styling with hover and focus states
- Color-coded filter types for visual distinction
- Responsive design that adapts to container width
- Dark mode support with appropriate color schemes
- Focus indicators for keyboard navigation
- Customizable through className props

### Custom Styling

You can customize the appearance using the className prop:

```tsx
<ControlCloud
  filters={filters}
  removeFilter={removeFilter}
  updateFilters={updateFilters}
  formatFieldName={formatFieldName}
  className="custom-control-cloud"
/>
```

## Keyboard Navigation

The ControlCloud component provides comprehensive keyboard navigation:

- **Arrow Keys**: Navigate between filter pills
- **Vim Keys**: 
  - `h` / `←`: Move left
  - `l` / `→`: Move right  
  - `j` / `↓`: Move down
  - `k` / `↑`: Move up
- **Delete/Backspace**: Remove focused filter pill
- **Tab**: Standard tab navigation
- **Escape**: Clear focus

## Keyboard Shortcuts

- **`⌥+⇧+D`**: Clear all filters and set a default time range (endTime = now, startTime = now - historicalWindow)
- **`⌥+⇧+C`**: Focus the first filter pill for keyboard navigation

## Accessibility

The ControlCloud component is built with accessibility in mind:

- **Keyboard Navigation**: Full keyboard support for all interactions
- **Screen Reader Support**: Proper ARIA labels and announcements
- **Focus Management**: Clear focus indicators and logical tab order
- **High Contrast**: Maintains proper contrast ratios
- **Semantic HTML**: Uses appropriate HTML elements and roles